
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Writing YAML job submission files &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="LAVA schema" href="pipeline-schema.html" />
    <link rel="prev" title="Lava Dispatcher Design" href="dispatcher-design.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/dispatcher-format.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Writing YAML job submission files</a><ul>
<li><a class="reference internal" href="#basics-of-the-yaml-format">Basics of the YAML format</a><ul>
<li><a class="reference internal" href="#basic-structure-for-job-submission">Basic structure for job submission</a></li>
<li><a class="reference internal" href="#sample-job-definition-for-a-kvm">Sample JOB definition for a KVM</a></li>
<li><a class="reference internal" href="#basic-structure-for-device-type-configuration">Basic structure for device_type configuration</a></li>
<li><a class="reference internal" href="#basic-structure-for-device-configuration">Basic structure for device configuration</a></li>
<li><a class="reference internal" href="#overriding-values-in-device-type-device-dictionary-and-the-job-context">Overriding values in device type, device dictionary and the job context</a><ul>
<li><a class="reference internal" href="#example-one">Example One</a></li>
<li><a class="reference internal" href="#example-two">Example Two</a></li>
<li><a class="reference internal" href="#example-three">Example Three</a></li>
</ul>
</li>
<li><a class="reference internal" href="#provide-environment-variables-for-the-device-in-the-job-description">Provide environment variables for the device in the job description</a></li>
<li><a class="reference internal" href="#pipeline-device-configuration">Pipeline Device Configuration</a></li>
<li><a class="reference internal" href="#viewing-the-device-dictionary">Viewing the Device Dictionary</a><ul>
<li><a class="reference internal" href="#on-scheduler-device-detail-page">On scheduler device detail page</a></li>
<li><a class="reference internal" href="#on-job-description-tab">On Job Description Tab</a></li>
<li><a class="reference internal" href="#as-admin">As Admin</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#dispatcher-actions">Dispatcher actions</a><ul>
<li><a class="reference internal" href="#mapping-deployment-actions-to-the-python-code">Mapping deployment actions to the python code</a></li>
<li><a class="reference internal" href="#deployment-actions">Deployment actions</a><ul>
<li><a class="reference internal" href="#supported-methods">Supported methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#boot-actions">Boot actions</a><ul>
<li><a class="reference internal" href="#id1">Supported methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#test-actions">Test actions</a></li>
<li><a class="reference internal" href="#metadata">Metadata</a></li>
<li><a class="reference internal" href="#submit-actions">Submit actions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="dispatcher-design.html" title="Previous Chapter: Lava Dispatcher Design"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; Lava Dispatch...</span>
    </a>
  </li>
  <li>
    <a href="pipeline-schema.html" title="Next Chapter: LAVA schema"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">LAVA schema &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="writing-yaml-job-submission-files">
<span id="dispatcher-yaml"></span><span id="index-0"></span><h1>Writing YAML job submission files<a class="headerlink" href="#writing-yaml-job-submission-files" title="Permalink to this heading">¶</a></h1>
<p><a class="reference external" href="http://yaml-online-parser.appspot.com/">Online YAML</a> Parser.</p>
<p>The submission format schema has not been created, so the detail may change and
errors in the content might not be picked up by the code, so take care when
preparing new files.</p>
<section id="basics-of-the-yaml-format">
<span id="yaml-job"></span><h2>Basics of the YAML format<a class="headerlink" href="#basics-of-the-yaml-format" title="Permalink to this heading">¶</a></h2>
<section id="basic-structure-for-job-submission">
<h3>Basic structure for job submission<a class="headerlink" href="#basic-structure-for-job-submission" title="Permalink to this heading">¶</a></h3>
<p>The basic structure of the submission YAML is:</p>
<ol class="arabic simple">
<li><p>parameters for the job</p></li>
<li><p>list of actions.</p></li>
</ol>
<p>The parameters for a job <strong>must include</strong>:</p>
<ol class="arabic simple">
<li><p>a <code class="docutils literal notranslate"><span class="pre">device_type</span></code></p></li>
<li><p>a <code class="docutils literal notranslate"><span class="pre">job_name</span></code></p></li>
</ol>
<p>Other parameters commonly supported include:</p>
<ol class="arabic simple">
<li><p><code class="docutils literal notranslate"><span class="pre">job_timeout</span></code> - the default for this is not currently decided, so always
specify a timeout for the job as a whole.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">action_timeout</span></code> - the default timeout for each individual action within
the job, unless an explicit timeout is set later in the YAML.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">priority</span></code></p></li>
</ol>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="timeouts.html#timeouts"><span class="std std-ref">Timeouts</span></a></p>
</div>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">device_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm</span>
<span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm-pipeline</span>
<span class="nt">job_timeout</span><span class="p">:</span>
<span class="w">  </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">15</span><span class="w">            </span><span class="c1"># timeout for the whole job (default: ??h)</span>
<span class="nt">action_timeout</span><span class="p">:</span>
<span class="w">  </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span><span class="w">         </span><span class="c1"># default timeout applied for each action; can be overridden in the action itself (default: ?h)</span>
<span class="nt">priority</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">medium</span>
</pre></div>
</div>
<p>In YAML, a list has a name, then a colon then an indented set of items, each of
which is preceded by a hyphen:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">actions</span><span class="p">:</span>
<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
</pre></div>
</div>
<p>Within a single action, like <code class="docutils literal notranslate"><span class="pre">deploy</span></code>, the parameters for that action are
expressed as a hash (or dict in python terminology). In YAML, this is presented
as an indented block of lines <strong>without</strong> a preceding hyphen.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">actions</span><span class="p">:</span>
<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">       </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">         </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">20</span>
<span class="w">       </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="w">       </span><span class="nt">images</span><span class="p">:</span>
<span class="w">         </span><span class="nt">rootfs</span><span class="p">:</span>
<span class="w">           </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://images.validation.linaro.org/kvm/standard/stretch-2.img.gz</span>
<span class="w">           </span><span class="nt">image_arg</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-drive format=raw,file={rootfs}</span>
<span class="w">           </span><span class="nt">compression</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gz</span>
</pre></div>
</div>
<p>This stanza describes a deployment strategy where the timeout for the entire
deployment action is 20 minutes, the deployment happens to <code class="docutils literal notranslate"><span class="pre">tmpfs</span></code> (it is up
to the python code for the strategy to work out what this means or fail the
validation of the pipeline). The deployment uses an <code class="docutils literal notranslate"><span class="pre">image</span></code> and the
deployment data to be used is that for a Debian system.</p>
<p>As the refactoring proceeds, other media can be supported in the <code class="docutils literal notranslate"><span class="pre">to</span></code>
instruction and other deployment types can be supported apart from <code class="docutils literal notranslate"><span class="pre">image</span></code>.
The final schema will need to express the available values for deployment
strategies, boot strategies and test strategies. A new strategy will need
support in the <a class="reference internal" href="#yaml-device-type"><span class="std std-ref">Basic structure for device_type configuration</span></a> for each type which supports that
strategy and in the python code to implement a pipeline for that strategy.</p>
<p>The rest of the actions are listed in the same way - the name of the top level
Strategy Action class as a list item, the parameters for that action class as a
dictionary.</p>
<p>Individual actions and parameters are described under <a class="reference internal" href="dispatcher-actions.html#dispatcher-actions"><span class="std std-ref">Dispatcher Action Reference</span></a>.</p>
</section>
<section id="sample-job-definition-for-a-kvm">
<h3>Sample JOB definition for a KVM<a class="headerlink" href="#sample-job-definition-for-a-kvm" title="Permalink to this heading">¶</a></h3>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">device_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm</span>

<span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm-pipeline</span>
<span class="nt">job_timeout</span><span class="p">:</span>
<span class="w">  </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">15</span><span class="w">            </span><span class="c1"># timeout for the whole job (default: ??h)</span>
<span class="nt">action_timeout</span><span class="p">:</span>
<span class="w">  </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span><span class="w">         </span><span class="c1"># default timeout applied for each action; can be overridden in the action itself (default: ?h)</span>
<span class="nt">priority</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">medium</span>

<span class="nt">actions</span><span class="p">:</span>

<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">       </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">         </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">20</span>
<span class="w">       </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="w">       </span><span class="nt">images</span><span class="p">:</span>
<span class="w">         </span><span class="nt">rootfs</span><span class="p">:</span>
<span class="w">           </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://images.validation.linaro.org/kvm/standard/stretch-2.img.gz</span>
<span class="w">           </span><span class="nt">image_arg</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-drive format=raw,file={rootfs}</span>
<span class="w">           </span><span class="nt">compression</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gz</span>

<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
<span class="w">       </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm</span>
<span class="w">       </span><span class="nt">media</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="w">       </span><span class="nt">failure_retry</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="w">       </span><span class="nt">prompts</span><span class="p">:</span>
<span class="w">         </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;linaro-test&#39;</span>
<span class="w">         </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;root@debian:~#&#39;</span>

<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="w">       </span><span class="nt">failure_retry</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
<span class="w">       </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm-basic-singlenode</span><span class="w">  </span><span class="c1"># is not present, use &quot;test $N&quot;</span>
<span class="w">       </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">         </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span><span class="w"> </span><span class="c1"># uses install:deps, so takes longer than singlenode01</span>
<span class="w">       </span><span class="nt">definitions</span><span class="p">:</span>
<span class="w">           </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="w">             </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
<span class="w">             </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lava-test-shell/smoke-tests-basic.yaml</span>
<span class="w">             </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">smoke-tests</span>
<span class="w">           </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="w">             </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
<span class="w">             </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lava-test-shell/single-node/singlenode03.yaml</span>
<span class="w">             </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">singlenode-advanced</span>
</pre></div>
</div>
<p>To see an example of how the sample YAML would look as a python snippet, use
the <a class="reference external" href="http://yaml-online-parser.appspot.com/">Online YAML</a> Parser.</p>
</section>
<section id="basic-structure-for-device-type-configuration">
<span id="yaml-device-type"></span><h3>Basic structure for device_type configuration<a class="headerlink" href="#basic-structure-for-device-type-configuration" title="Permalink to this heading">¶</a></h3>
<p>To take advantage of the new dispatcher design and to make the LAVA device
configuration more consistent, a new format is being created for the
device_type and device configuration files, again using YAML.</p>
<p>The device type outlines which strategies devices of this type are able to
support. The parameters and commands contained in the device_type configuration
will apply to all devices of this type.</p>
<p>The main block is a dictionary of actions. Each item is the name of the
strategy containing a list of arguments. All strategies require a <code class="docutils literal notranslate"><span class="pre">method</span></code> of
how that strategy can be implemented. The methods supported by this device type
appear as a list.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">actions</span><span class="p">:</span>
<span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">   </span><span class="c1"># list of deployment methods which this device supports</span>
<span class="w">   </span><span class="nt">methods</span><span class="p">:</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">image</span>
<span class="w">   </span><span class="c1"># no need for root-part, the MountAction will need to sort that out.</span>

<span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
<span class="w">   </span><span class="nt">prompts</span><span class="p">:</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;linaro-test&#39;</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;root@debian:~#&#39;</span>
<span class="w">   </span><span class="c1"># list of boot methods which this device supports.</span>
<span class="w">   </span><span class="nt">methods</span><span class="p">:</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">qemu</span>
<span class="w">   </span><span class="c1"># Action specific stanza</span>
<span class="w">   </span><span class="nt">command</span><span class="p">:</span>
<span class="w">     </span><span class="c1"># allows for the one type to support different binaries</span>
<span class="w">     </span><span class="nt">amd64</span><span class="p">:</span>
<span class="w">       </span><span class="nt">qemu_binary</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">qemu-system-x86_64</span>
<span class="w">   </span><span class="c1"># only overrides can be overridden in the Job</span>
<span class="w">   </span><span class="nt">overrides</span><span class="p">:</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">boot_cmds</span>
<span class="w">     </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">qemu_options</span>
<span class="w">   </span><span class="nt">parameters</span><span class="p">:</span>
<span class="w">     </span><span class="nt">boot_cmds</span><span class="p">:</span>
<span class="w">       </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">root</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/dev/sda1</span>
<span class="w">       </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">console</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ttyS0,115200</span>
<span class="w">     </span><span class="nt">qemu_options</span><span class="p">:</span>
<span class="w">       </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-nographic</span>
<span class="w">     </span><span class="nt">machine</span><span class="p">:</span>
<span class="w">        </span><span class="l l-Scalar l-Scalar-Plain">accel=kvm:tcg</span>
<span class="w">     </span><span class="nt">net</span><span class="p">:</span>
<span class="w">       </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">nic,model=virtio</span>
<span class="w">       </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user</span>
</pre></div>
</div>
</section>
<section id="basic-structure-for-device-configuration">
<span id="yaml-device"></span><h3>Basic structure for device configuration<a class="headerlink" href="#basic-structure-for-device-configuration" title="Permalink to this heading">¶</a></h3>
<p>Individual devices then populate parameters for a specified device_type.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">root_part</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
<span class="nt">architecture</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">amd64</span>
<span class="nt">memory</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">512</span>
</pre></div>
</div>
</section>
<section id="overriding-values-in-device-type-device-dictionary-and-the-job-context">
<span id="override-support"></span><h3>Overriding values in device type, device dictionary and the job context<a class="headerlink" href="#overriding-values-in-device-type-device-dictionary-and-the-job-context" title="Permalink to this heading">¶</a></h3>
<p>Administrators have full control over which values allow overrides, in the
following sequence:</p>
<ol class="arabic simple">
<li><p>the <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> can always override variables in the
device-type template by setting the variable name to a new value.</p></li>
<li><p>the job definition <strong>can</strong> override the device dictionary if the device
dictionary has no value set for that variable.</p></li>
<li><p>job definition can be <strong>allowed</strong> to override a variable from the device
dictionary <strong>only</strong> if the device type template specifically allows this by
allowing a variable from the job context to override a variable from the
device dictionary <strong>and only</strong> if the variable name in the job context
differs from the name used in the device dictionary.</p></li>
<li><p>Variables which should never be overridden can be included as simple text in
the device type template <strong>or</strong> always defined in the device dictionary for
all devices of that type. Remember to <a class="reference internal" href="review-criteria.html#essential-components"><span class="std std-ref">Only protect the essential components</span></a>.</p></li>
</ol>
<p>Where there is no sane default available for a device type template, the
validation of the pipeline <strong>must</strong> invalidate a job submission which results
in a missing value.</p>
<p>Currently, these override rules are not clearly visible from the UI, this will
change as development continues.</p>
<p>Device type templates exist as files in
<code class="file docutils literal notranslate"><span class="pre">/etc/lava-server/dispatcher-config/device-types</span></code> and can be modified by
the local administrators without losing changes when the packages are updated.</p>
<p>Device dictionaries exist in the database of the instance and can be modified
from the command line on the server - typically this will require <code class="docutils literal notranslate"><span class="pre">sudo</span></code>. See
<a class="reference internal" href="development.html#developer-access-to-django-shell"><span class="std std-ref">Developer access to django shell</span></a>.</p>
<section id="example-one">
<h4>Example One<a class="headerlink" href="#example-one" title="Permalink to this heading">¶</a></h4>
<p>For a device dictionary containing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">console_device</span><span class="p">:</span> <span class="s1">&#39;/dev/ttyO0&#39;</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The job is unable to set an override using the same variable name, so this will
fail to set <code class="file docutils literal notranslate"><span class="pre">/dev/ttyAMX0</span></code>:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">context</span><span class="p">:</span>
<span class="w">  </span><span class="nt">console_device</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/dev/ttyAMX0</span>
</pre></div>
</div>
<p>The final device configuration for that job will use <code class="file docutils literal notranslate"><span class="pre">/dev/ttyO0</span></code>.</p>
</section>
<section id="example-two">
<h4>Example Two<a class="headerlink" href="#example-two" title="Permalink to this heading">¶</a></h4>
<p>If the device dictionary contains no setting for <code class="docutils literal notranslate"><span class="pre">console_device</span></code>, then the
job context value can override the device type template default:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">context</span><span class="p">:</span>
<span class="w">  </span><span class="nt">console_device</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/dev/ttyAMX0</span>
</pre></div>
</div>
<p>The final device configuration for that job will use <code class="file docutils literal notranslate"><span class="pre">/dev/ttyAMX0</span></code>.</p>
</section>
<section id="example-three">
<h4>Example Three<a class="headerlink" href="#example-three" title="Permalink to this heading">¶</a></h4>
<p>If the device type template supports a specific job context variable, the job
can override the device dictionary. If the device type template contains:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">mac_address</span> <span class="o">=</span> <span class="n">tftp_mac_address</span> <span class="o">|</span> <span class="n">default</span><span class="p">(</span><span class="n">mac_address</span><span class="p">)</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The device dictionary can set:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">mac_address</span><span class="p">:</span> <span class="s1">&#39;00:01:73:69:5A:EF&#39;</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>If the job context sets:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">context</span><span class="p">:</span>
<span class="w">  </span><span class="nt">tftp_mac_address</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;FF:01:00:69:AA:CC&#39;</span>
</pre></div>
</div>
<p>Then the final device configuration for that job will use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;TFTP on MAC Address: FF:01:00:69:AA:CC&#39;</span>
</pre></div>
</div>
<p>If the job context does not define <code class="docutils literal notranslate"><span class="pre">tftp_mac_address</span></code>, the final device
configuration for that job will use:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;TFTP on MAC Address: 00:01:73:69:5A:EF&#39;</span>
</pre></div>
</div>
<p>This mechanism holds for variables set by the base template as well:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">base_kernel_args</span> <span class="o">=</span> <span class="n">extra_kernel_args</span> <span class="o">|</span> <span class="n">default</span><span class="p">(</span><span class="n">base_kernel_args</span><span class="p">)</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
</section>
</section>
<section id="provide-environment-variables-for-the-device-in-the-job-description">
<span id="job-environment-support"></span><h3>Provide environment variables for the device in the job description<a class="headerlink" href="#provide-environment-variables-for-the-device-in-the-job-description" title="Permalink to this heading">¶</a></h3>
<p>The job can define environment variables for the device:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">environment</span><span class="p">:</span>
<span class="w">  </span><span class="nt">FOO</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bar</span>
<span class="w">  </span><span class="nt">BAR</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">baz</span>
</pre></div>
</div>
<p>The variables are available in the test shell environment and can be referenced
in test scripts then.</p>
<p>For multinode jobs, the environment has to be defined for each multinode role
separately:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">protocols</span><span class="p">:</span>
<span class="w">  </span><span class="nt">lava-multinode</span><span class="p">:</span>
<span class="w">    </span><span class="nt">roles</span><span class="p">:</span>
<span class="w">      </span><span class="nt">node_a</span><span class="p">:</span>
<span class="w">        </span><span class="nt">environment</span><span class="p">:</span>
<span class="w">          </span><span class="nt">FOO</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bar</span>
<span class="w">      </span><span class="nt">node_b</span><span class="p">:</span>
<span class="w">        </span><span class="nt">environment</span><span class="p">:</span>
<span class="w">          </span><span class="nt">BAR</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">baz</span>
</pre></div>
</div>
<p>Environment variables defined in the job will override environment variables of
the same name defined in the device dictionary. See
<a class="reference internal" href="lava-scheduler-device-dictionary.html#device-dictionary-exported-parameters"><span class="std std-ref">Exported parameters</span></a>.</p>
</section>
<section id="pipeline-device-configuration">
<h3>Pipeline Device Configuration<a class="headerlink" href="#pipeline-device-configuration" title="Permalink to this heading">¶</a></h3>
<p>Device configuration is a combination of the <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> and the
<a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> template. A sample <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> (jinja2 child
template syntax) for nexus 10 will look like the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">extends</span> <span class="s1">&#39;nexus10.jinja2&#39;</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">adb_serial_number</span> <span class="o">=</span> <span class="s1">&#39;R32D300FRYP&#39;</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">fastboot_serial_number</span> <span class="o">=</span> <span class="s1">&#39;R32D300FRYP&#39;</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">fastboot_options</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;-u&#39;</span><span class="p">]</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">device_info</span> <span class="o">=</span> <span class="p">[{</span><span class="s1">&#39;board_id&#39;</span><span class="p">:</span> <span class="s1">&#39;R32D300FRYP&#39;</span><span class="p">}]</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">connection_command</span> <span class="o">=</span> <span class="s1">&#39;adb -s R32D300FRYP shell&#39;</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="nb">set</span> <span class="n">soft_reboot_command</span> <span class="o">=</span> <span class="s1">&#39;adb -s R32D300FRYP reboot bootloader&#39;</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The corresponding <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> template for nexus 10 is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">extends</span> <span class="s1">&#39;base.jinja2&#39;</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">block</span> <span class="n">body</span> <span class="o">%</span><span class="p">}</span>
<span class="n">adb_serial_number</span><span class="p">:</span> <span class="p">{{</span> <span class="n">adb_serial_number</span><span class="o">|</span><span class="n">default</span><span class="p">(</span><span class="s1">&#39;0000000000&#39;</span><span class="p">)</span> <span class="p">}}</span>
<span class="n">fastboot_serial_number</span><span class="p">:</span> <span class="p">{{</span> <span class="n">fastboot_serial_number</span><span class="o">|</span><span class="n">default</span><span class="p">(</span><span class="s1">&#39;0000000000&#39;</span><span class="p">)</span> <span class="p">}}</span>
<span class="n">fastboot_options</span><span class="p">:</span> <span class="p">{{</span> <span class="n">fastboot_options</span><span class="o">|</span><span class="n">default</span><span class="p">([])</span> <span class="p">}}</span>
<span class="n">device_info</span><span class="p">:</span> <span class="p">[{</span><span class="s1">&#39;board_id&#39;</span><span class="p">:</span> <span class="s1">&#39;R32D300FRYP&#39;</span><span class="p">}]</span>

<span class="p">{</span><span class="o">%</span> <span class="n">block</span> <span class="n">vland</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="c1"># skip the parameters dict at top level #}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endblock</span> <span class="o">%</span><span class="p">}</span>

<span class="n">actions</span><span class="p">:</span>
  <span class="n">deploy</span><span class="p">:</span>
    <span class="n">methods</span><span class="p">:</span>
      <span class="n">fastboot</span><span class="p">:</span>
    <span class="n">connections</span><span class="p">:</span>
      <span class="n">serial</span><span class="p">:</span>
      <span class="n">adb</span><span class="p">:</span>
  <span class="n">boot</span><span class="p">:</span>
    <span class="n">connections</span><span class="p">:</span>
      <span class="n">adb</span><span class="p">:</span>
    <span class="n">methods</span><span class="p">:</span>
      <span class="n">fastboot</span><span class="p">:</span>

<span class="p">{</span><span class="o">%</span> <span class="n">endblock</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> template extends <cite>base.jinja2</cite> which is the base
template used by all devices and has logic to replace some of the values
provided in the <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a>. For example, the following lines
within <cite>base.yaml</cite> will add connection command to the device:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="k">if</span> <span class="n">connection_command</span> <span class="o">%</span><span class="p">}</span>
<span class="n">commands</span><span class="p">:</span>
    <span class="n">connect</span><span class="p">:</span> <span class="p">{{</span> <span class="n">connection_command</span> <span class="p">}}</span>
<span class="p">{</span><span class="o">%</span> <span class="n">endif</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>See <code class="file docutils literal notranslate"><span class="pre">/etc/lava-server/dispatcher-config/device-types/base.yaml</span> <span class="pre">for</span> <span class="pre">the</span>
<span class="pre">complete</span> <span class="pre">content</span> <span class="pre">of</span> <span class="pre">`base.yaml</span></code></p>
<p>The above <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> and the <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> template are
combined together in order to form the device configuration which will look
like the following for a nexus 10 device:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">commands</span><span class="p">:</span>
<span class="w">    </span><span class="nt">connect</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">adb -s R32D300FRYP shell</span>
<span class="w">    </span><span class="nt">soft_reboot</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">adb -s R32D300FRYP reboot bootloader</span>
<span class="nt">adb_serial_number</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">R32D300FRYP</span>
<span class="nt">fastboot_serial_number</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">R32D300FRYP</span>
<span class="nt">fastboot_options</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&#39;-u&#39;</span><span class="p p-Indicator">]</span>
<span class="nt">device_info</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[{</span><span class="s">&#39;board_id&#39;</span><span class="p p-Indicator">:</span><span class="w"> </span><span class="s">&#39;R32D300FRYP&#39;</span><span class="p p-Indicator">}]</span>

<span class="nt">actions</span><span class="p">:</span>
<span class="w">  </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">    </span><span class="nt">methods</span><span class="p">:</span>
<span class="w">      </span><span class="nt">fastboot</span><span class="p">:</span>
<span class="w">    </span><span class="nt">connections</span><span class="p">:</span>
<span class="w">      </span><span class="nt">serial</span><span class="p">:</span>
<span class="w">      </span><span class="nt">adb</span><span class="p">:</span>
<span class="w">  </span><span class="nt">boot</span><span class="p">:</span>
<span class="w">    </span><span class="nt">connections</span><span class="p">:</span>
<span class="w">      </span><span class="nt">adb</span><span class="p">:</span>
<span class="w">    </span><span class="nt">methods</span><span class="p">:</span>
<span class="w">      </span><span class="nt">fastboot</span><span class="p">:</span>

<span class="nt">timeouts</span><span class="p">:</span>
<span class="w">  </span><span class="nt">actions</span><span class="p">:</span>
<span class="w">    </span><span class="nt">apply-overlay-image</span><span class="p">:</span>
<span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">120</span>
<span class="w">    </span><span class="nt">umount-retry</span><span class="p">:</span>
<span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">45</span>
<span class="w">    </span><span class="nt">lava-test-shell</span><span class="p">:</span>
<span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30</span>
<span class="w">    </span><span class="nt">power_off</span><span class="p">:</span>
<span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
<span class="w">  </span><span class="nt">connections</span><span class="p">:</span>
<span class="w">    </span><span class="nt">uboot-retry</span><span class="p">:</span>
<span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">60</span>
</pre></div>
</div>
<p>Use the following <a class="reference internal" href="lavacli.html#lavacli"><span class="std std-ref">lavacli</span></a> command to get the device
configuration in the command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">lavacli</span> <span class="o">--</span><span class="n">uri</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="o">/</span><span class="n">RPC2</span> <span class="n">devices</span> <span class="nb">dict</span> <span class="n">get</span> <span class="o">--</span><span class="n">render</span> <span class="n">qemu01</span>
</pre></div>
</div>
<p>which will download the device configuration and print it to stdout.</p>
</section>
<section id="viewing-the-device-dictionary">
<h3>Viewing the Device Dictionary<a class="headerlink" href="#viewing-the-device-dictionary" title="Permalink to this heading">¶</a></h3>
<section id="on-scheduler-device-detail-page">
<h4>On scheduler device detail page<a class="headerlink" href="#on-scheduler-device-detail-page" title="Permalink to this heading">¶</a></h4>
<p>The current <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> content is available on the scheduler
device detail page, under the <cite>Configuration</cite> property as a link called <cite>Device
Dictionary</cite>, e.g. for a device called <code class="docutils literal notranslate"><span class="pre">qemu01</span></code>, the URL to view this page
would be <code class="docutils literal notranslate"><span class="pre">/scheduler/device/qemu01/</span></code>.</p>
</section>
<section id="on-job-description-tab">
<h4>On Job Description Tab<a class="headerlink" href="#on-job-description-tab" title="Permalink to this heading">¶</a></h4>
<p>The information from <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> is also available from the <code class="docutils literal notranslate"><span class="pre">Job</span>
<span class="pre">Description</span></code> tab of a pipeline device. On the job details page e.g.
<a class="reference external" href="https://staging.validation.linaro.org/scheduler/job/136847">https://staging.validation.linaro.org/scheduler/job/136847</a> click on <code class="docutils literal notranslate"><span class="pre">Job</span>
<span class="pre">Description</span></code> tab, in which the first section gives information about the
device.</p>
</section>
<section id="as-admin">
<h4>As Admin<a class="headerlink" href="#as-admin" title="Permalink to this heading">¶</a></h4>
<ol class="arabic simple">
<li><p>See <a class="reference internal" href="pipeline-admin.html#viewing-device-dictionary-content"><span class="std std-ref">Viewing current device dictionary content</span></a></p></li>
<li><p>See also <a class="reference internal" href="pipeline-admin.html#updating-device-dictionary-using-xmlrpc"><span class="std std-ref">Using XML-RPC</span></a></p></li>
</ol>
</section>
</section>
</section>
<section id="dispatcher-actions">
<span id="mapping-dispatcher-actions"></span><span id="index-1"></span><h2>Dispatcher actions<a class="headerlink" href="#dispatcher-actions" title="Permalink to this heading">¶</a></h2>
<section id="mapping-deployment-actions-to-the-python-code">
<span id="mapping-yaml-to-code"></span><h3>Mapping deployment actions to the python code<a class="headerlink" href="#mapping-deployment-actions-to-the-python-code" title="Permalink to this heading">¶</a></h3>
<ol class="arabic simple">
<li><p>See also <a class="reference internal" href="dispatcher-design.html#code-flow"><span class="std std-ref">Following the code flow</span></a></p></li>
<li><p>Start at the parser. Ensure that the parser can find the top level Strategy
(the <code class="docutils literal notranslate"><span class="pre">name</span></code> in <code class="docutils literal notranslate"><span class="pre">action_data</span></code>).</p></li>
<li><p>If a specific strategy class exists and is included in the parser, the
Strategy class will be initialized with the current pipeline using the
<code class="docutils literal notranslate"><span class="pre">select</span></code> classmethod of the strategy. Only subclasses of the Strategy
class will be considered in the selection. The subclasses exist in the
actions/ directory in a sub-directory named after the strategy and a python
file named after the particular method.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">accepts</span></code> classmethod of the Strategy subclass determines whether this
subclass will be used for this job. Subclasses need to be imported into the
parser to be considered. (<code class="docutils literal notranslate"><span class="pre">pylint</span></code> will complain, so mark these import
lines to disable <code class="docutils literal notranslate"><span class="pre">unused-import</span></code>.)</p></li>
<li><p>The initialization of the Strategy subclass instantiates the top-level
Action for this Strategy.</p></li>
<li><p>The named Action then populates an internal pipeline when the Strategy
subclass adds the top-level Action to the job pipeline.</p></li>
<li><p>Actions cascade, adding more internal pipelines and more Actions until the
Strategy is complete. The Action instantiating the internal pipeline should
generally be constrained to just that task as this makes it easier to
implement RetryActions and other logical classes.</p></li>
<li><p>The parser moves on to the next Strategy.</p></li>
<li><p>If the parser has no explicit Strategy support, it will attempt to <code class="docutils literal notranslate"><span class="pre">find</span></code>
an Action subclass which matches the requested strategy. This support may be
removed once more strategies and Action sub-classes are defined.</p></li>
</ol>
</section>
<section id="deployment-actions">
<h3>Deployment actions<a class="headerlink" href="#deployment-actions" title="Permalink to this heading">¶</a></h3>
<section id="supported-methods">
<h4>Supported methods<a class="headerlink" href="#supported-methods" title="Permalink to this heading">¶</a></h4>
<ol class="arabic" id="image">
<li><p><strong>image</strong></p>
<p>An image deployment involves downloading the image and applying a LAVA
overlay to the image using loopback mounts. The LAVA overlay includes
scripts to automate the tests and the test definitions supplied to the
<code class="docutils literal notranslate"><span class="pre">test</span></code> strategy.</p>
<p>Example code block:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">20</span>
<span class="w">    </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="w">    </span><span class="nt">images</span><span class="p">:</span>
<span class="w">      </span><span class="nt">rootfs</span><span class="p">:</span>
<span class="w">        </span><span class="nt">url</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://images.validation.linaro.org/kvm/standard/stretch-2.img.gz</span>
<span class="w">        </span><span class="nt">image_arg</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-drive format=raw,file={rootfs}</span>
<span class="w">        </span><span class="nt">compression</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">gz</span>
</pre></div>
</div>
</li>
</ol>
</section>
</section>
<section id="boot-actions">
<h3>Boot actions<a class="headerlink" href="#boot-actions" title="Permalink to this heading">¶</a></h3>
<section id="id1">
<h4>Supported methods<a class="headerlink" href="#id1" title="Permalink to this heading">¶</a></h4>
<ol class="arabic">
<li><p><strong>kvm</strong></p>
<p>The KVM method uses QEMU to boot an image which has been downloaded and had
a LAVA overlay applied using an <a class="reference internal" href="#image"><span class="std std-ref">Image</span></a> deployment.</p>
<p>Example code block:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
<span class="w w-Error"> </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm</span>
<span class="w"> </span><span class="nt">media</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="w"> </span><span class="nt">failure_retry</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="w"> </span><span class="nt">prompts</span><span class="p">:</span>
<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;linaro-test&#39;</span>
<span class="w">   </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&#39;root@debian:~#&#39;</span>
</pre></div>
</div>
</li>
</ol>
</section>
</section>
<section id="test-actions">
<h3>Test actions<a class="headerlink" href="#test-actions" title="Permalink to this heading">¶</a></h3>
<p>Example code block:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="w">    </span><span class="nt">failure_retry</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
<span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">kvm-basic-singlenode</span><span class="w">  </span><span class="c1"># is not present, use &quot;test $N&quot;</span>
<span class="w">    </span><span class="c1"># only s, m &amp; h are supported.</span>
<span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span><span class="w"> </span><span class="c1"># uses install:deps, so takes longer than singlenode01</span>
<span class="w">    </span><span class="nt">definitions</span><span class="p">:</span>
<span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="w">          </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
<span class="w">          </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lava-test-shell/smoke-tests-basic.yaml</span>
<span class="w">          </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">smoke-tests</span>
<span class="w">        </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">repository</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://git.linaro.org/lava-team/lava-functional-tests.git</span>
<span class="w">          </span><span class="nt">from</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">git</span>
<span class="w">          </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">lava-test-shell/single-node/singlenode03.yaml</span>
<span class="w">          </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">singlenode-advanced</span>
</pre></div>
</div>
</section>
<section id="metadata">
<h3>Metadata<a class="headerlink" href="#metadata" title="Permalink to this heading">¶</a></h3>
<p>This is an optional parameter that can be added to any YAML job definition. It
takes a list of <code class="docutils literal notranslate"><span class="pre">key:</span> <span class="pre">value</span></code> arguments which can be used later to query the
test results and find similar jobs (incoming features).</p>
<p>Example:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">metadata</span><span class="p">:</span>
<span class="w">    </span><span class="nt">foo</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bar</span>
<span class="w">    </span><span class="nt">bar</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">foo</span>
</pre></div>
</div>
</section>
<section id="submit-actions">
<h3>Submit actions<a class="headerlink" href="#submit-actions" title="Permalink to this heading">¶</a></h3>
<p>There is no submit action in the pipeline. Results are transmitted live from
any class in the pipeline with support for declaring a result.</p>
<p>There is no meta-format for the results, results are based on the test job and
do not exist without reference to the test job.</p>
</section>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>